Note: Formatting of this document will appear better if displayed in
      a fixed Font (e.g. Courier)

WeatherCan  v2.2
================

Written because none of the other available weather scripts used weather
web sites that provided reasonable information for Canadian cities and
towns.  I think I now have most of the bugs out, so I figured there must
be other Canadian Samurize users who might like a better weather tool.

Although the web site provides information on many other U.S. and worldwide
cities, the selection of available data varies widely and the script may or
may not provide worthwhile data.  This is also true for many of the smaller
Canadian locations which may not contain a full set of data.  Best method is
to view the location in a Browser first to see what is available, then try 
selecting it with the script and crossing your fingers.   ;-))

Version Changes
---------------

1.1      Corrected setting the shell so the script operated correctly
         under Samurize. Thanks to gordep for the suggested correction,
         this had been driving me crazy for a long time.

         A few editorial corrections to the ReadMe file.

2.0      Bug Fixes:

           * WeatherCan.txt not being updated consistently.
               This may or may not have occured depending on the
               particular Internet settings for local Web page caching.
               Altered the Web page read function to cause bypassing of
               any local web caching, this will prevent the script from
               seeing the same page over and over from the cache and
               effectively thinking the page had not changed. (And
               thereby thinking that no re-creation of the
               WeatherCan.txt file was needed)

           * Occasional script failures when copying the .PNG files.
               Eliminated this problem by just not copying them anymore.
               The full path of the needed PNG is now output to the
               WeatherCan.txt file and can be picked up by Samurize just
               as any other data field and displayed as a dynamic PNG.

           * Enhancements and corrections to internal functions to better
             handle missing / optional data items on the web page.

         Enhancements / Changes:

           * Additional available data fields from the Web page

               * Additional almanac type data fields (Yesterdays
                 hi/lo, Averages, etc.

               * Wind speed and direction separated and a 0-100%
                 field added to support an analog compass rose
                 type display meter.

               * Split WEATHERWRAP constant into multiple ones for better
                 control of the text types.

               * Place the WeatherCan.txt file in the same directory as
                 that used for the WeatherCan PNG files rather than in
                 the System Temp\Samurize directory.

          * Current Samurize configs will require minor updates to pick
            up the correct line number within the WeatherCan.txt file
            because of the additional new data fields (as described below)
            as well as a path change to the new file location.  Sorry
            about that but it should only be a few minutes work.

2.2      Revisions to accomodate changes in the HTML formatting of the Web page data.

         Also added data line 60 in the WeatherCan.txt file. This line will contain
         the full narrative weather forecast for the next 5 periods.
  
Characteristics
---------------

* The WeatherCan.vbs script file contains only one Function - FetchPage.
  This function has no passed parameters, and has only one purpose, to
  fetch the desired web pages, extract the various weather data items from
  them, and then write all the extracted data as a plain TXT file containing
  1 line for each weather variable.  The function returns no output back
  to Samurize directly as part of the function call.

* A set of fixed-named PNG files are included to match those used by the
  Weather web site. These are normally stored in
  "C:\Program Files\Samurize\WeatherCan".

* The WeatherCan.txt file created by the script will be stored in the same
  Samurize sub-directory where the above WeatherCan PNG files are stored.
  This path is specified as a constant within the VBS file.

* All actual Samurize output is created by using a Text File meter and
  selecting the appropriate line number of the file (described below).

  This allows all weather variables, and weather PNG's,  to be included
  in Samurize via normal Text File Meters, each selecting just ONE line
  from within the file.  All Samurize meter styles (Text, Analog, Graphs,
  Progressbars, Dynamic PNGs, etc.) may be used as needed.

  Since all output is driven from Text File meters, it means that Samurize
  never needs to be restarted nor does the current config need to be
  reloaded to pick up the current data.

Installation
------------

* UnZip the WeatherCan.ZIP file and create as
  "C:\Program Files\Samurize\WeatherCan\"          (Preferred location).

* Copy the WeatherCan.vbs file to your normal Samurize Script directory.
  (Default C:\Program Files\Samurize\Scripts). At this point, your basic 
  installation is done

If you wish to try out the included sample Samurize Config, then do
the following:

* Copy the WeatherCan.INI file to your normal Samurize CONFIGS directory.
  (Default C:\Program Files\Samurize\Configs). Note this sample config is a 
  simple demo, don't expect a lot graphically. The WeatherCan.jpg shows what 
  the Config output should look like.

* The sample WeatherCan.INI file contains file paths to the location of
  various files, if you did not install to the Preferred location described
  above, then these need to be updated before  you can use the sample
  INI file. If you used the standard location, you're fine.

* Simply right click the Samurize Taskbar Icon, Choose Select Config File,
  and then Select WeatherCan.ini.

If you are ready to incorporate WeatherCan data into an existing Config:

* You will need to make two EDITs to customize for your system

* The WeatherCan.VBS file will need to be customized, there are comments
  in the file to assist you. MAKE SURE YOU DO THIS TO THE COPY IN YOUR
  NORMAL Samurize Script directory, not the one in the WeatherCan
  directory.

  * GETCITY needs to be altered to fetch YOUR desired city, the simplest 
    way to determine what's needed is to visit http://weatheroffice.ec.gc.ca
    and click your way to your city's details and note the resulting URL.
    The city code is usually the last 3 characters. 
     e.g. Hamilton Ontario URL is http://weatheroffice.ec.gc.ca/forecast/city_e.html?YHM 
    The code to enter for GETCITY would be "&city=YHM"

  * METRIC specifies whether to leave data values in Metric (True) or to convert them to
    'English' (i.e. inches, Fahrenheit, miles, etc.)

  * GMTREQ specifies the handling of the report time returned from the Web site which
    is provided as a GMT value.
        Specify GMTREQ = "99" to have the Date/Time converted to your systems
                              local time.
        Specify GMTREQ = "nn" to request a specific time zone offset to be converted to.
                              Note: values may be +ve or -ve or zero to keep GMT.

  * WEATHERCANDIRECTORY should be altered to the path where you copied the
    PNG images above if you did not use the Preferred destination mentioned
    above.

  * WRAPxxxxxxx constants controls the line length of the long text output
    strings. The script will word-wrap and insert Samurize %b line breaks
    as needed.

    * WRAPCURRENT controls the wrapping of the Current weather conditions

    * WRAPFORECASTSHORT controls the wrapping of the 5 period forecasts.

    * WRAPFORECASTLONG controls the wrapping of the full narrative 5 period forecast.

    (Note the WRAP values are in 'Characters')

  * In the Samurize Config editor, create a Dummy Samurize meter whose sole
    purpose is to cause the WeatherCan script to execute periodically.

    * Select Add Meter, then Select Add Active Script

    * Under Active Script, select WeatherCan.VBS and then select the FetchPage
      function.

    * Set 'Run every x min' to 30 to 60 minutes.

    * Clear the Meter Text properties since the function will NOT be returning
      any values.

    * Click the 'Test Script' button. Your modified script should run.

    * Check the WeatherCan.txt file in the
      C:\Program Files\Samurize\WeatherCan directory with a text editor
      (e.g. NotePad). You should see the data for the city you selected when
      you edited the WeatherCan.vbs file.

  * At this point you are ready to include the data in the WeatherCan.txt
    file into your normal Samurize configuration.  Use the description at
    the end of this document to determine the exact line number within the
    file to be used in your config.

    * For each actual weather data item you wish to include in your config:

      * Select Add Meter, and then select Add Text File.

      * Under Text File Properties, Select
        "C:\Program Files\Samurize\WeatherCan\WeatherCan.txt" (assuming 
        it's default location).

      * Under Text File Properties, Set 'Number of Lines:' to 1.

      * Under Text File Properties, Set 'Read Line' to the desired line number
        as shown in the file description which follows below.

      * Under Meter Properties, Set the Draw type, etc. to whatever you desire
        to format the data. e.g. color, fonts, alignment, graphics settings
        (graphs, analog, etc.)


Contents of the WeatherCan.TXT File
-----------------------------------

  All output from the WeatherCan script is created as simple text lines
in this file.  A sample file is shown below with comments added on the
right describing each lime.  (The comments obviously are NOT written
in the actual file.)

Data                                Line #
----                                ------

2 Dec. 2003 at 11:00 AM EST         01 - Date/Time of this information
Hamilton - Canada                   02 - City for which this data applies
7:32                                03 - Today's Sunrise
16:46                               04 - Today's Sunset
14:04                               05 - Today's Moonrise
1:17                                06 - Today's Moonset
-0.3C                              07 - Historical Average High
-7.5C                              08 - Historical Average Low
-3.9C                              09 - Historical Average Mean
10.1C                              10 - Yesterday's High
-2.5C                              11 - Yesterday's Low
0.0 mm                              12 - Yesterday's Total Precipitation
                                    13 - For future expansion
                                    14 - For future expansion
C:\Program Files\Samurize\WeatherCan\12.png	15 - Curr. Weather PNG path
Mainly Sunny                        16 - Curr. Weather conditions (Text)
-5C                                17 - Current temperature
102.9kPa                            18 - Current barometric pressure
24km                                19 - Current visibility
60%                                 20 - Current humidity
-11C                               21 - Current dew point
                                         (Will not appear if WindChill or Humidex are
                                          provided in the next two lines)
WindChill                           22 - "WindChill" if line 23 contains
                                         a valid WindChill value,
                                         "Humidex" if line 23 contains
                                         a valid Humidex value,
                                         Blanks if neither WindChill or
                                         Humidex are available.
-9                                  23 - Calculated WindChill or Humidex
                                         value or blank if neither is
                                         available.
SW@25km                             24 - Current wind description
SW                                  25 - Current wind direction
25                                  26 - Current wind speed numerically
12.5                                27 - Numerical value (0 thru 100) to be 
                                         used for an analog wind compass
                                    28 - For future expansion
                                    29 - For future expansion
C:\Program Files\Samurize\WeatherCan\13.png	30 - Forecast 1 - Weather PNG path
Tuesday                             31 - Forecast 1 - Full day name
Today                               32 - Forecast 1 - Short name
-3                                 33 - Forecast 1 - Forecast hi/lo temperatures
Chance of flurries POP 40 %         34 - Forecast 1 - Text
                                    35 - For future expansion
C:\Program Files\Samurize\WeatherCan\08.png	36 - Forecast 2 - Weather PNG path
Tuesday night                       37 - Forecast 2 - Full day name
Tonight                             38 - Forecast 2 - Short name
-9                                 39 - Forecast 2 - Forecast hi/lo temperatures
Chance of flurries POP 40 %         40 - Forecast 2 - Text
                                    41 - For future expansion
C:\Program Files\Samurize\WeatherCan\02.png	42 - Forecast 3 - Weather PNG path
Wednesday                           43 - Forecast 3 - Full day name
Wed                                 44 - Forecast 3 - Short name
-1/-9                             45 - Forecast 3 - Forecast hi/lo temperatures
Sunny with cloudy periods           46 - Forecast 3 - Text
                                    47 - For future expansion
C:\Program Files\Samurize\WeatherCan\05.png	48 - Forecast 4 - Weather PNG path
Thursday                            49 - Forecast 4 - Full day name
Thu                                 50 - Forecast 4 - Short name
0/-5                              51 - Forecast 4 - Forecast hi/lo temperatures
Sunny                               52 - Forecast 4 - Text
                                    53 - For future expansion
C:\Program Files\Samurize\WeatherCan\12.png	54 - Forecast 5 - Weather PNG path
Friday                              55 - Forecast 5 - Full day name
Fri                                 56 - Forecast 5 - Short name
-2/-11                            57 - Forecast 5 - Forecast hi/lo temperatures
Sunny                               58 - Forecast 5 - Text
                                    59 - For future expansion
                                    60 - Full narrative text forecast. (sample below) TODAY..%bA mix of sun and cloud. 30 percent chance of %bflurries. Wind  west 30 km/h. High minus 5.%bTONIGHT..%bCloudy periods. Clearing near midnight. Wind %bnorthwest 20  km/h becoming light overnight. %bLow minus 9.%bTHURSDAY..%bSunny. High minus 5.%bFRIDAY..%bSnow mixed with rain. Low minus 6. High plus 2.%bSATURDAY..%bCloudy. 60 percent chance of flurries. Low %bminus 4. High  minus 2.%bSUNDAY..%bA mix of sun and cloud. 30 percent chance of %bflurries. Low  minus 10. High minus 4.%bNORMALS FOR THE PERIOD..%bLow minus 12. High minus 3.%b


Any problems / questions?  Post something as a comment to the download area (best) 
or in the forums or you can contact me directly (gddeluca@bigfoot.com).

